/*
 * Copyright the original author or authors.
 * 
 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.mozilla.org/MPL/MPL-1.1.html
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.blitscreen.render 
{
	import flash.display.BitmapData;

	/**
	 * A <code>RenderQueue</code> object manage rendering on a specified
	 * output <code>BitmapData</code>. The queue is composed by any number
	 * of <code>RenderPass</code> objects. Each pass realize a specific
	 * work on the bitmap in order to perform the complete render.
	 * 
	 * @author 	Cédric Néhémie
	 * @see		RenderPass
	 */
	public interface RenderQueue
	{
		/**
		 * Realizes the render process. The render process
		 * consist in calling the <code>render</code> method
		 * of each pass of this queue.
		 * <p>
		 * Generally, concret class will choose to not process
		 * any render as long as there is no output defined.
		 * </p>
		 */
		function render() : void;
		
		/**
		 * Returns the number of <code>RenderPass</code> in this
		 * queue.
		 * 
		 * @return <code>Number</code> of <code>RenderPass</code>	
		 * 		   in this queue.
		 */
		function size () : Number;
		
		/**
		 * Adds the passed-in render pass at the end of the this
		 * render queue.
		 * <p>
		 * Concret class which implements the <code>RenderQueue</code>
		 * interface can choose to allow more than one entry for the
		 * same <code>RenderPass</code> object. If the concret class
		 * allow only one occurence for a pass, it have to throw an 
		 * <code>IllegalStateException</code> when trying to add
		 * a pass which is already in this queue.
		 * </p><p>
		 * Concret class which implements the <code>RenderQueue</code>
		 * interface can choose to allow <code>null</code> entries. 
		 * If not, the class have to throw an <code>NullPointerException</code>
		 * when the user try to add <code>null</code>.
		 * </p>
		 * @param  	pass 	<code>RenderPass</code> object to be added
		 * @throws 	IllegalStateException - The passed-in pass object is
		 * 			already register in this queue object.
		 * @throws 	NullPointerException - The passed-in <code>pass</code>
		 * 			argument is <code>null</code>.
		 * @see		#contains()
		 * @see		#remove()
		 */
		function add ( pass : RenderPass ) : void;
		/**
		 * Removes the passed-in <code>RenderPass</code> object from this
		 * <code>RenderQueue</code>.
		 * <p>
		 * Concret class have to throw an <code>IllegalStateException</code>
		 * when trying to remove a pass which is not in this queue.
		 * </p><p>
		 * Concret class which implements the <code>RenderQueue</code>
		 * interface can choose to allow more than one entry for the
		 * same pass. In that case the concret class have to remove
		 * only the first occurence found for each call of the
		 * <code>remove</code> method.
		 * </p><p>
		 * Concret class which implements the <code>RenderQueue</code>
		 * interface can choose to allow <code>null</code> entries. 
		 * If not, the class have to throw an <code>NullPointerException</code>
		 * when the user try to remove <code>null</code>.
		 * </p>
		 * @param  	pass <code>RenderPass</code>
		 * @throws 	IllegalStateException - The passed-in render pass is not
		 * 			registered in this queue.
		 * @throws 	NullPointerException - The passed-in <code>pass</code>
		 * 			argument is <code>null</code>.
		 * @see		#add()
		 * @see		#contains()
		 */
		function remove ( pass : RenderPass ) : void;
		/**
		 * Returns <code>true</code> if the passed-in
		 * <code>RenderPass</code> object is contained
		 * in this queue.
		 * <p>
		 * Concret class which allow <code>null</code>
		 * entries have to return <code>true</code> if
		 * there is at least one entry containing 
		 * <code>null</code> in this queue.
		 * </p> 
		 * @param pass <code>RenderPass</code>
		 * @see	  #add()
		 * @see	  #remove()
		 */
		function contains ( pass : RenderPass ) : Boolean;

		/**
		 * Defines the output <code>BitmapData</code> onto
		 * which this queue will operate.
		 * 
		 * @param screen <code>BitmapData</code> object 
		 * 				 which will be the output for this 
		 * 				 queue.
		 */
		function setOutput ( screen : BitmapData ) : void;
		/**
		 * Returns a reference to the <code>BitmapData</code>
		 * object which is currently defined as output for
		 * this queue.
		 * 
		 * @return <code>BitmapData</code> output for this 
		 * 		   <code>RenderQueue</code>
		 */
		function getOutput () : BitmapData;
		/**
		 * Returns <code>true</code> if this queue has a defined output,
		 * <code>false</code> otherwise.
		 * 
		 * @return 	<code>true</code> if this queue has a defined output,
		 * 			<code>false</code> otherwise.
		 */
		function hasOutput () : Boolean;
		
		/**
		 * Returns the duration of the last call of the <code>render</code>
		 * method in milliseconds.
		 *  
		 * @return 	<code>Number</code> of milliseconds of the last call of
		 * 		   	<code>render</code> method.
		 * @see		#render()
		 */
		function getLastRenderTime() : Number;
	}
}
